/*-------------------------------------------------------------------------
 *
 * tuplestore.h
 *	  临时元组存储的通用例程。
 *
 * 此模块处理元组的临时存储，目的包括
 * 例如 Materialize 节点、hashjoin 批处理文件等。它本质上是
 * tuplesort.c 的简化版本；它不对元组进行排序，
 * 只能存储和回放一系列元组。但是，
 * 由于不需要排序，它可以在所有元组写入之前开始读取序列。
 * 对于游标来说，这特别有用，
 * 因为它允许在已扫描的查询部分内随机访问，而不必处理
 * 潜在的扫描直至完成。
 * 此外，可以支持多个独立的读取指针。
 *
 * 如果数据超过调用者指定的
 * 空间限制，将使用临时文件处理数据。
 *
 * 从 Postgres 8.2 开始，存储的只是 MinimalTuples；
 * 调用者不能期望在回放的元组中获得有效的系统列。
 * 此外，我们已更改 API，使元组返回在 TupleTableSlots 中，
 * 以便进行检查，防止尝试访问系统列。
 *
 * Portions Copyright (c) 1996-2022, PostgreSQL Global Development Group
 * Portions Copyright (c) 1994, Regents of the University of California
 *
 * src/include/utils/tuplestore.h
 *
 *-------------------------------------------------------------------------
 */
#ifndef TUPLESTORE_H
#define TUPLESTORE_H

#include "executor/tuptable.h"


/* Tuplestorestate 是一种不透明类型，其细节在 tuplestore.c 之外是未知的。 */
typedef struct Tuplestorestate Tuplestorestate;

/*
 * 当前我们只需要存储 MinimalTuples，但支持 IndexTuples 和/或裸 Datums 的相同行为也很简单。
 */

extern Tuplestorestate *tuplestore_begin_heap(bool randomAccess,
											  bool interXact,
											  int maxKBytes);

extern void tuplestore_set_eflags(Tuplestorestate *state, int eflags);

extern void tuplestore_puttupleslot(Tuplestorestate *state,
									TupleTableSlot *slot);
extern void tuplestore_puttuple(Tuplestorestate *state, HeapTuple tuple);
extern void tuplestore_putvalues(Tuplestorestate *state, TupleDesc tdesc,
								 Datum *values, bool *isnull);

/* 向后兼容宏 */
#define tuplestore_donestoring(state)	((void) 0)

extern int	tuplestore_alloc_read_pointer(Tuplestorestate *state, int eflags);

extern void tuplestore_select_read_pointer(Tuplestorestate *state, int ptr);

extern void tuplestore_copy_read_pointer(Tuplestorestate *state,
										 int srcptr, int destptr);

extern void tuplestore_trim(Tuplestorestate *state);

extern bool tuplestore_in_memory(Tuplestorestate *state);

extern bool tuplestore_gettupleslot(Tuplestorestate *state, bool forward,
									bool copy, TupleTableSlot *slot);

extern bool tuplestore_advance(Tuplestorestate *state, bool forward);

extern bool tuplestore_skiptuples(Tuplestorestate *state,
								  int64 ntuples, bool forward);

extern int64 tuplestore_tuple_count(Tuplestorestate *state);

extern bool tuplestore_ateof(Tuplestorestate *state);

extern void tuplestore_rescan(Tuplestorestate *state);

extern void tuplestore_clear(Tuplestorestate *state);

extern void tuplestore_end(Tuplestorestate *state);

#endif							/* TUPLESTORE_H */
